<?php
//
//  VictoryCMS - Content managment system and framework.
//  Copyright (C) 2009  Lewis Gunsch
//
//  This file is part of VictoryCMS.
//
//  VictoryCMS is free software: you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation, either version 3 of the License, or
//  (at your option) any later version.
//
//  VictoryCMS is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with VictoryCMS.  If not, see <http://www.gnu.org/licenses/>.

/**
 * VictoryCMS - VcmsDB
 * 
 * @license http://www.gnu.org/licenses/gpl.html
 * @author Lewis Gunsch
 * @filesource
 * @package DBAbstraction
 */

/**
 * Outlines the functions necessary to interface with a
 * VictoryCMS database.
 *
 * @package DBAbstraction
 *
 */
abstract class VcmsDB {

	/**	The database connection resource. */
	protected $connection;

	/** A database query result set resource. */
	protected $result;

	/** Constructs a new VcmsDB object. */
	public function __construct() {
		$this->getConnected();
	}

	/** Destroys the VcmsDB object. */
	public function __destruct() {

		$this->cleanUp();
	}

	/**
	 * Returns a connection to the database. This uses
	 * the db_hostname, db_user, and db_passwd values to connect to
	 * the database and return a new database connection.
	 *
	 * @return void Nothing
	 */
	abstract public function getConnected();

	/**
	 * Returns true if VmcsDB object is connected to the database
	 * and false if not.
	 *
	 * @return boolean True if connected to the DB, and false if not.
	 */
	abstract public function isConnected();

	/**
	 * This cleans any data so it is ready to be inserted into
	 * the database, such as escaping all quotes.
	 *
	 * @return The cleaned data string.
	 */
	abstract public function cleanData($data);

	/**
	 * Runs the database query with the current database connection, or
	 * if there is no current connection it creates one. Use fetchResults()
	 * to retrieve the results of the query.
	 *
	 * @param $queryName The name of the query to use from the SqlQuerySet.
	 * @param $querySet The SqlQuerySet containing the requested query.
	 * @param $dataSet The data to be sent into the sql query, will be sanitized first.
	 * @return void
	 * 
	 * @todo this should support transaction sets!
	 */
	abstract public function runQuery( $queryName, SqlSet $querySet, array $dataSet = NULL);

	/**
	 * Fetches one row of the current query into an array
	 * or if there is no more rows or a row does not exists
	 * then it returns FALSE.
	 *
	 * @param $row Row number in result to fetch. Rows are numbered from 0
	 * upwards. If omitted, next row is fetched.
	 * @return an array representing a row
	 */
	abstract public function fetchRow($row = -1);

	/**
	 * Fetches a specific field name from the current query result
	 * set with the given offset or false on error.
	 *
	 * @param $offSet the column offset to use staring from 0.
	 * @return string field name of current result set column offSet or
	 * false on error.
	 */
	abstract public function fetchFieldName($offSet);

	/**
	 * Fetches the type of a specific field from the current query
	 * result the given offset or false on error.
	 *
	 * @param $offSet the column offset to use staring from 0.
	 * @return field type of current result set column offSet or
	 * false on error.
	 */
	abstract public function fetchFieldType($offSet);

	/**
	 * Fetches the number of rows in the result set from 
	 * the current query. It will return -1 on error.
	 * @return integer The number of rows in the result set, -1 on error.
	 */
	abstract public function fetchNumRows();
	
	/**
	 * Fetches the number of fields in the result set from
	 * the current query. It will return -1 on error.
	 * @return integer The number of fields in the result set, -1 on error.
	 */
	abstract public function fetchNumFields();
	
	/**
	 * Closes the database connection
	 * and frees the results of any database query.
	 */
	abstract public function cleanUp();

}
?>